home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1996 March / macformat-035.iso / Shareware City / Developers / MoreFiles 1.4.1 / FullPath.p < prev    next >
Encoding:
Text File  |  1995-12-21  |  7.4 KB  |  168 lines  |  [TEXT/CWIE]
  1. UNIT FullPath;
  2.  
  3. {    Apple Macintosh Developer Technical Support                                }
  4. {                                                                            }
  5. {    Routines for dealing with full pathnames... if you really must.            }
  6. {                                                                            }
  7. {    by Jim Luther, Apple Developer Technical Support Emeritus                }
  8. {                                                                            }
  9. {    File:        FullPath.p                                                    }
  10. {                                                                            }
  11. {    Copyright © 1995 Apple Computer, Inc.                                    }
  12. {    All rights reserved.                                                    }
  13. {                                                                            }
  14. {    You may incorporate this sample code into your applications without        }
  15. {    restriction, though the sample code has been provided "AS IS" and the    }
  16. {    responsibility for its operation is 100% yours.  However, what you are    }
  17. {    not permitted to do is to redistribute the source as "DSC Sample Code"    }
  18. {    after having made changes. If you're going to re-distribute the source,    }
  19. {    we require that you make it clear in the source that the code was        }
  20. {    descended from Apple Sample Code, but that you've made changes.            }
  21.  
  22.  
  23. {    IMPORTANT NOTE:                                                            }
  24. {                                                                            }
  25. {    The use of full pathnames is strongly discouraged. Full pathnames are    }
  26. {    particularly unreliable as a means of identifying files, directories    }
  27. {    or volumes within your application, for two primary reasons:            }
  28. {                                                                            }
  29. {    •     The user can change the name of any element in the path at            }
  30. {        virtually any time.                                                    }
  31. {    •    Volume names on the Macintosh are *not* unique. Multiple            }
  32. {        mounted volumes can have the same name. For this reason, the use of    }
  33. {        a full pathname to identify a specific volume may not produce the    }
  34. {        results you expect. If more than one volume has the same name and    }
  35. {        a full pathname is used, the File Manager currently uses the first    }
  36. {        mounted volume it finds with a matching name in the volume queue.    }
  37. {                                                                            }
  38. {    In general, you should use a file’s name, parent directory ID, and        }
  39. {    volume reference number to identify a file you want to open, delete,    }
  40. {    or otherwise manipulate.                                                }
  41. {                                                                            }
  42. {    If you need to remember the location of a particular file across        }
  43. {    subsequent system boots, use the Alias Manager to create an alias        }
  44. {    record describing the file. If the Alias Manager is not available, you    }
  45. {    can save the file’s name, its parent directory ID, and the name of the    }
  46. {    volume on which it’s located. Although none of these methods is            }
  47. {    foolproof, they are much more reliable than using full pathnames to        }
  48. {    identify files.                                                            }
  49. {                                                                            }
  50. {    Nonetheless, it is sometimes useful to display a file’s full pathname    }
  51. {    to the user. For example, a backup utility might display a list of full    }
  52. {    pathnames of files as it copies them onto the backup medium. Or, a        }
  53. {    utility might want to display a dialog box showing the full pathname of    }
  54. {    a file when it needs the user’s confirmation to delete the file. No        }
  55. {    matter how unreliable full pathnames may be from a file-specification    }
  56. {    viewpoint, users understand them more readily than volume reference        }
  57. {    numbers or directory IDs.                                                }
  58. {                                                                            }
  59. {    The following technique for constructing the full pathname of a file is    }
  60. {    intended for display purposes only. Applications that depend on any        }
  61. {    particular structure of a full pathname are likely to fail on alternate    }
  62. {    foreign file systems or under future system software versions.            }
  63.  
  64.  
  65. INTERFACE
  66.  
  67. USES
  68.     Files;
  69.  
  70. {***************************************************************************}
  71.  
  72.  
  73.     FUNCTION GetFullPath (vRefNum: INTEGER;
  74.                                     dirID: LONGINT;
  75.                                     name: StringPtr;
  76.                                     VAR fullPathLength: INTEGER;
  77.                                     VAR fullPath: Handle): OSErr;
  78. {    Get a full pathname to a volume, directory or file.                        }
  79. {    The GetFullPath function builds a full pathname to the specified        }
  80. {    object. The full pathname is returned in the newly created handle        }
  81. {    fullPath and the length of the full pathname is returned in                }
  82. {    fullPathLength. Your program is responsible for disposing of the        }
  83. {    fullPath handle.                                                        }
  84. {                                                                            }
  85. {    vRefNum            input:    Volume specification.                            }
  86. {    dirID            input:    Directory ID.                                    }
  87. {    name            input:    Pointer to object name, or nil when dirID        }
  88. {                            specifies a directory that's the object.        }
  89. {    fullPathLength    output:    The number of characters in the full pathname.    }
  90. {                            If the function fails to create a full            }
  91. {                            pathname, it sets fullPathLength to 0.            }
  92. {    fullPath        output:    A handle to the newly created full pathname        }
  93. {                            buffer. If the function fails to create a        }
  94. {                            full pathname, it sets fullPath to NULL.        }
  95.  
  96.  
  97. {***************************************************************************}
  98.  
  99.  
  100.     FUNCTION FSpGetFullPath ({CONST}VAR spec: FSSpec;
  101.                                     VAR fullPathLength: INTEGER;
  102.                                     VAR fullPath: Handle): OSErr;
  103. {    Get a full pathname to a volume, directory or file.                        }
  104. {    The GetFullPath function builds a full pathname to the specified        }
  105. {    object. The full pathname is returned in the newly created handle        }
  106. {    fullPath and the length of the full pathname is returned in                }
  107. {    fullPathLength. Your program is responsible for disposing of the        }
  108. {    fullPath handle.                                                        }
  109. {                                                                            }
  110. {    spec            input:    An FSSpec record specifying the object.            }
  111. {    fullPathLength    output:    The number of characters in the full pathname.    }
  112. {                            If the function fails to create a full            }
  113. {                            pathname, it sets fullPathLength to 0.            }
  114. {    fullPath        output:    A handle to the newly created full pathname        }
  115. {                            buffer. If the function fails to create a        }
  116. {                            full pathname, it sets fullPath to NULL.        }
  117.  
  118.  
  119. {***************************************************************************}
  120.  
  121.  
  122.     FUNCTION FSpLocationFromFullPath (fullPathLength: INTEGER;
  123.                                     fullPath: Ptr;
  124.                                     VAR spec: FSSpec): OSErr;
  125. {    Get a FSSpec from a full pathname.                                        }
  126. {    The FSpLocationFromFullPath function returns a FSSpec to the object        }
  127. {    specified by full pathname. This function requires the Alias Manager.    }
  128. {                                                                            }
  129. {    fullPathLength    input:    The number of characters in the full pathname    }
  130. {                            of the target.                                    }
  131. {    fullPath        input:    A pointer to a buffer that contains the full    }
  132. {                            pathname of the target. The full pathname        }
  133. {                            starts with the name of the volume, includes    }
  134. {                            all of the directory names in the path to the    }
  135. {                            target, and ends with the target name.            }
  136. {    spec            output:    An FSSpec record specifying the object.            }
  137.  
  138.  
  139. {***************************************************************************}
  140.  
  141.  
  142.     FUNCTION LocationFromFullPath (fullPathLength: INTEGER;
  143.                                     fullPath: Ptr;
  144.                                     VAR vRefNum: INTEGER;
  145.                                     VAR parID: LONGINT;
  146.                                     VAR name: Str31): OSErr;
  147. {    Get a FSSpec from a full pathname.                                        }
  148. {    The FSpLocationFromFullPath function returns a FSSpec to the object        }
  149. {    specified by full pathname. This function requires the Alias Manager.    }
  150. {                                                                            }
  151. {    fullPathLength    input:    The number of characters in the full pathname    }
  152. {                            of the target.                                    }
  153. {    fullPath        input:    A pointer to a buffer that contains the full    }
  154. {                            pathname of the target. The full pathname        }
  155. {                            starts with the name of the volume, includes    }
  156. {                            all of the directory names in the path to the    }
  157. {                            target, and ends with the target name.            }
  158. {    vRefNum            output:    The volume reference number.                    }
  159. {    parID            output:    The parent directory ID of the specified object.}
  160. {    name            output:    The name of the specified object.                }
  161.  
  162.  
  163. {***************************************************************************}
  164.  
  165.  
  166. IMPLEMENTATION
  167.  
  168. END.